home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / tcl / library.man < prev    next >
Encoding:
Text File  |  1992-02-25  |  12.1 KB  |  267 lines
  1.  
  2.  
  3.  
  4. library           Tcl Command Language Library            library
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE
  11.      library - standard library of Tcl procedures
  12.  
  13. SSYYNNOOPPSSIISS
  14.      aauuttoo__eexxeeccookk _c_m_d                                               |
  15.      aauuttoo__llooaadd _c_m_d                                                 |
  16.      aauuttoo__mmkkiinnddeexx _d_i_r _p_a_t_t_e_r_n                                      |
  17.      aauuttoo__rreesseett                                                    |
  18.      ppaarrrraayy _a_r_r_a_y_N_a_m_e                                              |
  19.      uunnkknnoowwnn _c_m_d ?_a_r_g _a_r_g ...?                                     |
  20.  
  21. _________________________________________________________________  |
  22.  
  23.  
  24. IINNTTRROODDUUCCTTIIOONN                                                       |
  25.      Tcl includes a library of Tcl procedures for commonly-needed  |
  26.      functions.   The  procedures  defined in the Tcl library are  |
  27.      generic ones suitable for use  by  many  different  applica-  |
  28.      tions.   The  location of the Tcl library is returned by the  |
  29.      iinnffoo lliibbrraarryy command.  In addition to the Tcl library,  each  |
  30.      application  will  normally  have its own library of support  |
  31.      procedures as well;  the location of this  library  is  nor-  |
  32.      mally given by the value of the $$aappppLLiibbrraarryy global variable.  |
  33.  
  34.      To access the procedures in the Tcl library, an  application  |
  35.      should  source the file iinniitt..ttccll in the library, for example  |
  36.      with the Tcl command                                          |
  37.  
  38.           ssoouurrccee [[iinnffoo lliibbrraarryy]]//iinniitt..ttccll                           |
  39.      This will define the uunnkknnoowwnn procedure and arrange  for  the  |
  40.      other  procedures to be loaded on-demand using the auto-load  |
  41.      mechanism defined below.                                      |
  42.  
  43.  
  44. CCOOMMMMAANNDD PPRROOCCEEDDUURREESS                                                 |
  45.      The following procedures are provided in the Tcl library:     |
  46.  
  47.      aauuttoo__eexxeeccookk _c_m_d                                                    ||
  48.           Determines  whether  there is an executable file by the  |
  49.           name _c_m_d.  This command examines the directories in the  |
  50.           current  search  path  (given  by  the PATH enviornment  |
  51.           variable) to see if there is an executable  file  named  |
  52.           _c_m_d  in any of those directories.  If so, it returns 1;  |
  53.           if not it returns 0.  AAuuttoo__eexxeecc  remembers  information  |
  54.           about  previous  searches in an array named aauuttoo__eexxeeccss;  |
  55.           this avoids the path search in  future  calls  for  the  |
  56.           same  _c_m_d.  The command aauuttoo__rreesseett may be used to force  |
  57.           aauuttoo__eexxeeccookk to forget its cached information.            |
  58.  
  59.      aauuttoo__llooaadd _c_m_d                                                      ||
  60.           This  command attempts to load the definition for a Tcl  |
  61.           procedure named _c_m_d.  To do this, it searches an  _a_u_t_o-  |
  62.  
  63.  
  64.  
  65. Sprite v.1.0       Printed:  February 25, 1992                  1
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72. library           Tcl Command Language Library            library
  73.  
  74.  
  75.  
  76.           _l_o_a_d  _p_a_t_h, which is a list of one or more directories.  |
  77.           The auto-load path is  given  by  the  global  variable  |
  78.           $$aauuttoo__ppaatthh  if  it  exists.   If there is no $$aauuttoo__ppaatthh  |
  79.           variable, then the TCLLIBPATH environment  variable  is  |
  80.           used,  if it exists.  Otherwise the auto-load path con-  |
  81.           sists of just the Tcl library directory.   Within  each  |
  82.           directory  in  the  auto-load path there must be a file  |
  83.           ttccllIInnddeexx that describes the procedures defined in  that  |
  84.           directory  and  the  file  in  which  each procedure is  |
  85.           defined.  The ttccllIInnddeexx file should  be  generated  with  |
  86.           the  aauuttoo__mmkkiinnddeexx command.  If _c_m_d is found in an index  |
  87.           file, then the appropriate script is ssoouurrcceed to  create  |
  88.           the  procedure.  The aauuttoo__llooaadd command returns 1 if the  |
  89.           script was successfully sourced  and  _c_m_d  now  exists.  |
  90.           The  command  returns 0 if there was no index entry for  |
  91.           _c_m_d or if the script didn't actually define  _c_m_d  (e.g.  |
  92.           because index information is out of date).  If an error  |
  93.           occurs while processing the script, then that error  is  |
  94.           returned.   AAuuttoo__llooaadd  only reads the index information  |
  95.           once and saves it  in  the  array  aauuttoo__iinnddeexx;   future  |
  96.           calls  to  aauuttoo__llooaadd  check for _c_m_d in the array rather  |
  97.           than re-reading the  index  files.   The  cached  index  |
  98.           information may be deleted with the command aauuttoo__rreesseett.  |
  99.           This will force the next aauuttoo__llooaadd  command  to  reload  |
  100.           the index database from disk.                            |
  101.  
  102.      aauuttoo__mmkkiinnddeexx _d_i_r _p_a_t_t_e_r_n                                           ||
  103.           Generates  an index suitable for use by aauuttoo__llooaadd.  The  |
  104.           command searches _d_i_r for all files  whose  names  match  |
  105.           _p_a_t_t_e_r_n  (matching is done with the gglloobb command), gen-  |
  106.           erates an index  of  all  the  Tcl  command  procedures  |
  107.           defined in all the matching files, and stores the index  |
  108.           information in a file named ttccllIInnddeexx in _d_i_r.  For exam-  |
  109.           ple, the command                                         |
  110.  
  111.                aauuttoo__mmkkiinnddeexx ffoooo **..ttccll                              |
  112.  
  113.           will read all the ..ttccll files in  subdirectory  ffoooo  and  |
  114.           generate a new index file ffoooo//ttccllIInnddeexx.                  |
  115.  
  116.           AAuuttoo__mmkkiinnddeexx parses the Tcl  scripts  in  a  relatively  |
  117.           unsophisticated  way:   if  any  line contains the word  |
  118.           pprroocc as its first characters then it is assumed to be a  |
  119.           procedure  definition  and the next word of the line is  |
  120.           taken as the procedure's name.   Procedure  definitions  |
  121.           that  don't  appear  in this way (e.g. they have spaces  |
  122.           before the pprroocc) will not be indexed.                    |
  123.  
  124.      aauuttoo__rreesseett                                                         ||
  125.           Destroys  all the information cached by aauuttoo__eexxeeccookk and  |
  126.           aauuttoo__llooaadd.  This information will be re-read from  disk  |
  127.           the next time it is needed.                              |
  128.  
  129.  
  130.  
  131. Sprite v.1.0       Printed:  February 25, 1992                  2
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138. library           Tcl Command Language Library            library
  139.  
  140.  
  141.  
  142.      ppaarrrraayy _a_r_r_a_y_N_a_m_e                                                   ||
  143.           Prints  on  standard output the names and values of all  |
  144.           the elements in the array _a_r_r_a_y_N_a_m_e.  AArrrraayyNNaammee must be  |
  145.           a global array.                                          |
  146.  
  147.      uunnkknnoowwnn _c_m_d ?_a_r_g _a_r_g ...?                                          ||
  148.           This  procedure  is  invoked  automatically  by the Tcl  |
  149.           interpreter whenever the  name  of  a  command  doesn't  |
  150.           exist.  The uunnkknnoowwnn procedure receives as its arguments  |
  151.           the name and arguments of the missing command.  UUnnkknnoowwnn  |
  152.           first  calls aauuttoo__llooaadd to load a procedure for the com-  |
  153.           mand.  If this succeeds, then it executes the  original  |
  154.           command  with its original arguments.  If the auto-load  |
  155.           fails then uunnkknnoowwnn calls aauuttoo__eexxeeccookk to see if there is  |
  156.           an  executable file by the name _c_m_d.  If so, it invokes  |
  157.           the Tcl eexxeecc command with _c_m_d and all the _a_r_g_s as argu-  |
  158.           ments.   If  _c_m_d can't be auto-executed, uunnkknnoowwnn checks  |
  159.           to see if _c_m_d is a unique abbreviation for an  existing  |
  160.           Tcl  command.   If  so, it expands the command name and  |
  161.           executes  the  command  with  the  original  arguments.  |
  162.           Finally,  if none of the above efforts has been able to  |
  163.           execute the command, uunnkknnoowwnn generates an error return.  |
  164.           If the global variable aauuttoo__nnoollooaadd is defined, then the  |
  165.           auto-load step is  skipped.   If  the  global  variable  |
  166.           aauuttoo__nnooeexxeecc  is  defined  then  the  auto-exec  step is  |
  167.           skipped.  Under normal circumstances the  return  value  |
  168.           from  uunnkknnoowwnn is the return value from the command that  |
  169.           was eventually executed.                                 |
  170.  
  171.  
  172. VVAARRIIAABBLLEESS                                                          |
  173.      The following global variables are defined or  used  by  the  |
  174.      procedures in the Tcl library:                                |
  175.  
  176.      aauuttoo__eexxeeccss                                                         ||
  177.           Used by aauuttoo__eexxeeccookk to record information about whether  |
  178.           particular commands exist as executable files.           |
  179.  
  180.      aauuttoo__iinnddeexx                                                         ||
  181.           Used  by  aauuttoo__llooaadd  to save the index information read  |
  182.           from disk.                                               |
  183.  
  184.      aauuttoo__nnooeexxeecc                                                        ||
  185.           If  set  to any value, then uunnkknnoowwnn will not attempt to  |
  186.           auto-exec any commands.                                  |
  187.  
  188.      aauuttoo__nnoollooaadd                                                        ||
  189.           If  set  to any value, then uunnkknnoowwnn will not attempt to  |
  190.           auto-load any commands.                                  |
  191.  
  192.      aauuttoo__ppaatthh                                                          ||
  193.           If  set,  then  it must contain a valid Tcl list giving  |
  194.  
  195.  
  196.  
  197. Sprite v.1.0       Printed:  February 25, 1992                  3
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204. library           Tcl Command Language Library            library
  205.  
  206.  
  207.  
  208.           directories to search during auto-load operations.       |
  209.  
  210.      eennvv((TTCCLLLLIIBBPPAATTHH))                                                    ||
  211.           If  set,  then  it must contain a valid Tcl list giving  |
  212.           directories  to  search  during  auto-load  operations.  |
  213.           This variable is only used if aauuttoo__ppaatthh is not defined.  |
  214.  
  215.      uunnkknnoowwnn__aaccttiivvee                                                     ||
  216.           This  variable is set by uunnkknnoowwnn to indicate that it is  |
  217.           active.  It is used  to  detect  errors  where  uunnkknnoowwnn  |
  218.           recurses  on  itself infinitely.  The variable is unset  |
  219.           before uunnkknnoowwnn returns.                                  |
  220.  
  221.  
  222. KKEEYYWWOORRDDSS                                                           |
  223.      auto-exec, auto-load, library, unknown
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263. Sprite v.1.0       Printed:  February 25, 1992                  4
  264.  
  265.  
  266.  
  267.